<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>chmod</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_001_440">&nbsp;</a>NAME</h4><blockquote>
chmod - change mode of a file
</blockquote><h4><a name = "tag_000_001_441">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="systypes.h.html">sys/types.h</a>&gt;
#include &lt;<a href="sysstat.h.html">sys/stat.h</a>&gt;

int chmod(const char *<i>path</i>, mode_t <i>mode</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_001_442">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>chmod()</i>
function changes S_ISUID, S_ISGID,
S_ISVTX
and the file permission bits of the
file named by the pathname pointed to by the
<i>path</i>
argument to the corresponding bits in the
<i>mode</i>
argument.
The effective user ID of the process must match the
owner of the file or the process must have appropriate privileges
in order to do this.
<p>
S_ISUID, S_ISGID and the file permission bits
are described in
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>.
<p>
If a directory is writable and the mode bit S_ISVTX is set on
the directory, a process may remove or rename files within that
directory only if one or more of the following is true:
<ul>
<p>
<li>
The effective user ID of the process is the same as that of the owner ID of
the file.
<p>
<li>
The effective user ID of the process is the same as that of the owner ID of
the directory.
<p>
<li>
The process has appropriate privileges.
<p>
</ul>
<p>
If the S_ISVTX bit is set on a non-directory file, the behaviour is
unspecified.
<p>
If the calling process does not have appropriate privileges,
and if the group ID
of the file does not match the effective group ID
or one of the supplementary group
IDs and if the file is a regular file, bit S_ISGID (set-group-ID
on execution) in the file's mode will be cleared upon successful return
from
<i>chmod()</i>.
<p>
Additional implementation-dependent restrictions may cause the S_ISUID
and S_ISGID bits in
<i>mode</i>
to be ignored.
<p>
The effect on file descriptors for files open at the time of a call to
<i>chmod()</i>
is implementation-dependent.
<p>
Upon successful completion,
<i>chmod()</i>
will mark for update the
<i>st_ctime</i>
field of the file.
</blockquote><h4><a name = "tag_000_001_443">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion, 0 is returned.  Otherwise, -1 is returned and
<i>errno</i>
is set to indicate the error.
If -1 is returned, no change to the file mode will occur.
</blockquote><h4><a name = "tag_000_001_444">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>chmod()</i>
function will fail if:
<dl compact>

<dt>[EACCES]<dd>
Search permission is denied on a component of the path prefix.

<dt>[ELOOP]<dd>
Too many symbolic links were encountered in resolving <i>path</i>.

<dt>[ENAMETOOLONG]<dd>

The length of the
<i>path</i>
argument exceeds {PATH_MAX} or a pathname component is longer than
{NAME_MAX}.

<dt>[ENOTDIR]<dd>
A component of the path prefix is not a directory.

<dt>[ENOENT]<dd>
A component of <i>path</i> does not name an existing file
or <i>path</i> is an empty string.

<dt>[EPERM]<dd>
The effective user ID
does not match the owner of the file and the
process does not have appropriate privileges.

<dt>[EROFS]<dd>
The named file resides on a read-only file system.

</dl>
<p>
The
<i>chmod()</i>
function
may fail if:
<dl compact>

<dt>[EINTR]<dd>
A signal was caught during execution of the function.

<dt>[EINVAL]<dd>
The value of the
<i>mode</i>
argument is invalid.

<dt>[ENAMETOOLONG]<dd>

Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

</dl>
</blockquote><h4><a name = "tag_000_001_445">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_001_446">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
In order to ensure that the S_ISUID and S_ISGID
bits are set, an application requiring this should use
<i><a href="stat.html">stat()</a></i>
after a successful
<i>chmod()</i>
to verify this.
<p>
Any file descriptors currently open by any process on the file may become
invalid if the mode of the file is changed to a value which would deny access
to that process. One situation where this could occur is on a stateless
file system.
</blockquote><h4><a name = "tag_000_001_447">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_001_448">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="chown.html">chown()</a></i>,
<i><a href="mkdir.html">mkdir()</a></i>,
<i><a href="mkfifo.html">mkfifo()</a></i>,
<i><a href="open.html">open()</a></i>,
<i><a href="stat.html">stat()</a></i>,
<i><a href="statvfs.html">statvfs()</a></i>,
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>,
<i><a href="systypes.h.html">&lt;sys/types.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from Issue 1 of the SVID.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

